feat: well_manager + well estimator by tjb-ltk · Pull Request #3972 · GEOS-DEV/GEOS

tjb-ltk · 2026-02-13T15:09:34Z

Replaces PR #3735 and extends PR #3971

Overview

This PR introduces

An improved well schema layout and code refactor better suited for well modeling. The previous implementation primarily targeted Jacobian generation requirements for the coupled reservoir and well system.
The well estimator is used to select the active well constraint by solving the well system assuming fixed reservoir conditions and selecting the constraint with the highest or lowest well flowing pressure.
- the estimator is applied at beginning of Jacobian assembly of the coupled system
- frequency determined via input setting
- estimator is a data member of WellControl and a tailed version of PhysicsSolver for wells
- logic underpins future capability to replace the segmented well model with other formulations

This is a breaking change, detailed migration instructions and migration script are posted at #4081

…broken

…aint class hierachy , 3) Remove all old constraint handling methods/variables, 4) it compiles ...

…lephase still needs testing

…t compositionalMultiphaseFlow/soreideWhitson/1D_100cells/1D_benchmark.xml

… to fixed and inputFiles regenerated

…d convert compositionalMultiphaseFlow/soreideWhitson/1D_100cells/1D_benchmark.xml" This reverts commit fa61ab1.

…well initialization vagaries assoiated with useSurfaceConditions=0

…for resvol constraint, compositional only

…te well state

joshua-white · 2026-07-15T00:20:57Z

      // set the reference well element where the BHP control is applied
-      wellControls.setReferenceGravityCoef( refElev * gravVector[2] );
+      wellControls.setReferenceGravityCoef( refElev * gravVector[2] );  // tjb remove


actually remove?

Removed and setup access to bhp constraint value. The pattern could be improved but in a different PR.

victorapm · 2026-07-17T00:31:02Z

+  // 13.4) Make sure there is at least one non-BHP constraint
+  bool const rate_match_found = std::any_of( constraints.begin(), constraints.end(), [&bhp_type]( const auto & constraint_tuple )
+  {
+    return std::get< 1 >( constraint_tuple ) != bhp_type;
+  } );
+  GEOS_THROW_IF( !rate_match_found,
+                 GEOS_FMT( "Missing rate constraint for {} well {}",
+                           (isProducerWell ? "producer" : "injector"), getName() ),


if a well has phaseVolRate while defining only a total-volume rate constraint, this check would flag things are good, but i guess initialization would hit issues later.

not sure about the distinction between has phaseVolRate and defining a totalVolrate... its just verifying if a rate constraint is present... current code needs 1 bhp and at least 1 rate constraint ... error checking on a specific type is done in constraint object

victorapm · 2026-07-17T00:34:40Z

+  string const bhp_type = isProducerWell ? MinimumBHPConstraint::catalogName() : MaximumBHPConstraint::catalogName();
+  bool const no_match_found = std::none_of( constraints.begin(), constraints.end(), [&bhp_type]( const auto & constraint_tuple )
+  {
+    return std::get< 1 >( constraint_tuple ) == bhp_type;
+  } );
+  GEOS_THROW_IF( no_match_found,


When the sole BHP or rate constraint has constraintActive=0, these existence checks still accept it, while getBHPConstraint and the rate-list helpers filter it out. Subsequent selection either dereferences null or erases an end() iterator because the current constraint is absent from the active list.

Not sure if this address your comment... for all current models constraintActive = 1. The addition of this flag was needed for 2 workflows, wellheadpressure, where the simulator can impose an "internal constraint" and the underpinning of future functionality where a well can be assigned producer and injection constraints, which then come into consideration when only the well type changes, versus the need to define 2 wells with same perforation information. For either the code will need to ensure that an active pressure and rate constraint are present.

jafranc · 2026-07-17T16:02:37Z

+   * @param domain the physical domain object
+   */
+  void chopNegativeDensities( DomainPartition & domain );
+#if 0


should it be gone ?

yes .. gone

jafranc · 2026-07-17T16:12:11Z

+  m_useMass( false ),
+  m_useTotalMassEquation( 1 ),
+  m_isThermal( 0 ),
+  m_isCompositional( true ),


should'nt it be an integer and registered for restart ? what happen if we want to restard a non-compositional well ?

The variable is an internal flag set for initial and restart runs. I'm guessing the integratedTests would fail if it was set for restarts.

jafranc · 2026-07-17T16:26:25Z

+  array1d< real64 > localResidualNorm, wellResidalNorm;
+  array1d< real64 > localResidualNormalizer;
+
+  if( isThermal() )


Sticking to conventionm shouldn't it be set by NDOF or so ?

Yes, it would add the volume balance.. I will create a separate PR so any changes are associated with a specific change.

jafranc · 2026-07-17T16:32:38Z

+          if( wellResidalNorm[i] > localResidualNorm[i] )
+          {
+            localResidualNorm[i] = wellResidalNorm[i];
+          }


Suggested change

if( wellResidalNorm[i] > localResidualNorm[i] )

{

localResidualNorm[i] = wellResidalNorm[i];

}

localResidualNorm[i] = LvArray::math::max( localResidualNorm[i], wellResidualNorm[i] );

jafranc · 2026-07-17T16:33:56Z

+      // step 1: compute the norm in the subRegion
+      if( wellControls.isWellOpen( ) )
+      {
+        wellResidalNorm = wellControls.calculateLocalWellResidualNorm( time_n,


Suggested change

wellResidalNorm = wellControls.calculateLocalWellResidualNorm( time_n,

wellResidualNorm = wellControls.calculateLocalWellResidualNorm( time_n,

jhuang2601

@tjb-ltk Great job!

Please update the branch with latest develop repo, which will fix the following failures for readthedoc build:

WARNING: Error, no command xref target from index:QuickStart
WARNING: Error, no command xref target from index:Tutorials
WARNING: Error, no command xref target from index:BasicExamples
WARNING: Error, no command xref target from index:AdvancedExamples
WARNING: Error, no command xref target from index:UserGuide

jhuang2601 · 2026-07-21T14:02:18Z

+  // setup fluid model
+  string const & fluidName = subRegion.getReference< string >( viewKeyStruct::fluidNamesString() );
+  constitutive::MultiFluidBase & fluid = subRegion.getConstitutiveModel< constitutive::MultiFluidBase >( fluidName );
+  std::cout << "Validating fluid model for well " << getName() << "..." << m_useMass << std::endl;


Suggested change

std::cout << "Validating fluid model for well " << getName() << "..." << m_useMass << std::endl;

remove?

jhuang2601 · 2026-07-21T14:05:24Z

+    std::cout << " Well: " << subRegion.getName() << "   Est Attempt: " << dtAttempt
+              << ", ConfigurationIter: " << configurationLoopIter
+              << ", NewtonIter: " << newtonIter
+              << ", Residual Norm: " << residualNorm << std::endl;


This is inside a Newton iteration loop and will spam output every iteration.
Remove it? or guard by a log level?

jhuang2601 · 2026-07-21T14:07:18Z

+#include "fileIO/Outputs/OutputBase.hpp"
+#include "physicsSolvers/fluidFlow/wells/WellFields.hpp"

+#include "functions/FunctionManager.hpp"


Suggested change

#include "functions/FunctionManager.hpp"

remove this duplicate, as it has already been added in line 37

jhuang2601 · 2026-07-21T14:12:29Z

+    setApplyDefaultValue( 0 ).
    setInputFlag( InputFlags::OPTIONAL ).
-    setDescription( "Name of the BHP table when the rate is a time dependent function" );
+    setDescription( "Flag to esitmate well solution prior to coupled reservoir and well solve." );


Suggested change

setDescription( "Flag to esitmate well solution prior to coupled reservoir and well solve." );

setDescription( "Flag to estimate well solution prior to coupled reservoir and well solve." );

jhuang2601 · 2026-07-21T14:13:11Z

-  }
-  /// ViewKey struct for the WellControls class
-  viewKeysWellControls;
+    /// string key for the esitmate well solution flag


Suggested change

/// string key for the esitmate well solution flag

/// string key for the estimate well solution flag

jhuang2601 · 2026-07-21T15:33:21Z

@@ -345,8 +401,6 @@
      scale="0.1"/>
  </FieldSpecifications>


Suggested change

</FieldSpecifications>

</FieldSpecifications>

jhuang2601 · 2026-07-21T15:33:31Z


-  <!-- SPHINX_TUT_DEAD_OIL_EGG_FIELD_SPECS_END -->
-  <!-- SPHINX_TUT_DEAD_OIL_EGG_OUTPUTS -->
  <Outputs>


Suggested change

<Outputs>



<Outputs>

jhuang2601 · 2026-07-21T15:33:46Z

    <Restart
      name="restartOutput"/>
-
  </Outputs>


Suggested change

</Outputs>

</Outputs>

jhuang2601 · 2026-07-21T15:33:58Z


-  <!-- SPHINX_TUT_DEAD_OIL_EGG_OUTPUTS_END -->
-  <!-- SPHINX_TUT_DEAD_OIL_EGG_TASKS -->
  <Tasks>


Suggested change

<Tasks>



<Tasks>

jhuang2601 · 2026-07-21T15:34:10Z

      objectPath="ElementRegions/wellRegion4/wellRegion4UniqueSubRegion"
-      fieldName="wellElementMixtureConnectionRate"/>
+      fieldName="wellElementConnectionRate"/>
  </Tasks>


Suggested change

</Tasks>

</Tasks>

jhuang2601

@tjb-ltk Great job!

Please update the branch with latest develop repo, which will fix the following failures for readthedoc build:

WARNING: Error, no command xref target from index:QuickStart
WARNING: Error, no command xref target from index:Tutorials
WARNING: Error, no command xref target from index:BasicExamples
WARNING: Error, no command xref target from index:AdvancedExamples
WARNING: Error, no command xref target from index:UserGuide

tjb-ltk and others added 30 commits September 29, 2025 16:50

1) new constraint schema, 2) resturcture well jac assem loops

f9db9fd

fix merge errors

a9cd276

fix integrate errors

c59b1a6

rel mode fix

48aabd4

1) remove old code, 2) test different constraint org, 3) singlephase …

a85ee1d

…broken

1) SinglePhaseWell adopts new constraint convention, 2) Change constr…

8366922

…aint class hierachy , 3) Remove all old constraint handling methods/variables, 4) it compiles ...

fix constraint sign and normalizers

4f49bf1

1) compositional_multiphase_wells_1d.xml matches geos branch, 2) sing…

2e82b49

…lephase still needs testing

compressible_single_phase_wells_1d.xml matches geos branch

6281018

improve naming conventions for well constriant files and classes

205889f

fix reference to 'internal' is ambiguous error

b6ae5ef

1) well constraint schema script, 2) converted xmls, 3) Failed conver…

fa61ab1

…t compositionalMultiphaseFlow/soreideWhitson/1D_100cells/1D_benchmark.xml

schema

292c90f

1)fixes for catalogue registration, 2) xml convert script still needs…

d4eb504

… to fixed and inputFiles regenerated

fix liq rate schema

bd3d0cf

Revert "1) well constraint schema script, 2) converted xmls, 3) Faile…

723c2bc

…d convert compositionalMultiphaseFlow/soreideWhitson/1D_100cells/1D_benchmark.xml" This reverts commit fa61ab1.

xml with new constraint schema, try 2

e39ccf1

merge devel

d0fcf79

remove extra ;

8b21d69

remove :

470a7ff

fix constraint schema, phase name on totalvol constraint not allowed

b8a90f4

update well constraint schema

94fc9ad

1) expose method for unit tests, 2) update unittests accordingly

17047bd

schema change

c6a349f

1) remove unused vars , add missing constriant type in selector

1c03220

reintroduce control keyword option to be consistent with previous in …

b5f6c5d

…well initialization vagaries assoiated with useSurfaceConditions=0

updated schema

c43657e

add back control keyword

e78ef18

add control schema to unit tests

b000ed4

uncrustify should be automated

a319e0e

minor cleanup

19f2305

joshua-white reviewed Jul 9, 2026

View reviewed changes

Comment thread src/coreComponents/integrationTests/wellsTests/testThermalInjWell.cpp

joshua-white reviewed Jul 9, 2026

View reviewed changes

Comment thread ...coreComponents/physicsSolvers/fluidFlow/wells/kernels/CompositionalMultiphaseWellKernels.hpp Outdated

joshua-white reviewed Jul 9, 2026

View reviewed changes

Comment thread src/coreComponents/physicsSolvers/fluidFlow/wells/kernels/SinglePhaseWellKernels.cpp Outdated

tjb-ltk added 5 commits July 10, 2026 10:34

Merge branch 'develop' into feature/byer3/wm_we

5e2935e

more devel merge induced changes

ade7016

1) pr review changes, 2) code refactor to support regionstats needed …

005081f

…for resvol constraint, compositional only

region statistics interface fixes 1) cut timestep , 2) estimator upda…

e0f350a

…te well state

schema update

c0390d6

joshua-white reviewed Jul 15, 2026

View reviewed changes

joshua-white approved these changes Jul 15, 2026

View reviewed changes

integrated test update due to schema and data structure changes

ea74e49

herve-gross approved these changes Jul 16, 2026

View reviewed changes